---
title: 'Simulation'
description: 'Configure advanced settings for running OASIS simulations'
---

# Simulation Settings

OASIS provides powerful tools for running social media simulations with AI agents. This guide covers the advanced settings for configuring and running simulations.

## Time Settings

OASIS supports flexible time handling for simulations through the `Clock` class. This allows you to control how time progresses in your simulation.

```python
from oasis.clock.clock import Clock
from datetime import datetime

# Create a clock with time magnification factor
sandbox_clock = Clock(magnification_factor=60)  # 60x speed

# Create a platform with the custom clock
platform = Platform(
    db_path="./data/simulation.db",
    channel=channel,
    sandbox_clock=sandbox_clock,
    start_time=datetime.now(),  # Set the simulation start time
    # Additional parameters...
)
```

### Clock Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `magnification_factor` | `int` | How much faster simulation time passes compared to real-time |
| `start_time` | `datetime` | The starting time for the simulation (default: current time) |

## Simulation Controls

### Environment Actions

You can control the simulation by sending `EnvAction` objects to the environment during each step:

```python
from oasis import EnvAction, SingleAction, ActionType

# Create a custom intervention
action = SingleAction(
    agent_id=0,
    action=ActionType.CREATE_POST,
    args={"content": "Test post for the simulation"}
)

# Create an environment action to activate specific agents
env_action = EnvAction(
    activate_agents=[0, 1, 2, 3, 4],  # Only these agents will be active
    intervention=[action]              # Optional interventions
)

# Step the environment with the action
await env.step(env_action)
```

### Activating Agents

You can control which agents are active during each simulation step:

- Activate specific agents: `activate_agents=[1, 3, 5, 7, 9]`
- Activate all agents: `EnvAction()` (empty action with no parameters)

### Empty Action

To simply advance the simulation with all agents active and no interventions:

```python
empty_action = EnvAction()  # Activate all agents with no intervention
await env.step(empty_action)
```

## Agent Models

OASIS supports various LLM backends through the CAMEL framework. You can configure agents to use different models:

```python
from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType

# Create models for agents
openai_model = ModelFactory.create(
    model_platform=ModelPlatformType.OPENAI,
    model_type=ModelType.GPT_4O_MINI,
)

# Use with multiple models (load balancing)
vllm_model_1 = ModelFactory.create(
    model_platform=ModelPlatformType.VLLM,
    model_type="qwen-2",
    url="http://127.0.0.1:8001",
)
vllm_model_2 = ModelFactory.create(
    model_platform=ModelPlatformType.VLLM,
    model_type="qwen-2",
    url="http://127.0.0.1:8002",
)
models = [vllm_model_1, vllm_model_2]  # List of models for load balancing

# Create environment with the models
env = oasis.make(
    platform=platform,
    agent_profile_path="./data/profiles/users.csv",
    agent_models=models,  # Pass a single model or list of models
    available_actions=available_actions,
)
```

## Agent Profiles

OASIS supports different agent profile formats depending on the platform type:

### Twitter Agent Profiles (CSV format)

For Twitter-like platforms, agent profiles are typically stored in CSV files:

```
user_id,user_name,name,bio,friend_count,follower_count,statuses_count,created_at
0,user0,User Zero,I am user zero with interests in technology.,100,150,500,2023-01-01
1,user1,User One,Tech enthusiast and coffee lover.,200,250,1000,2023-01-02
```

### Reddit Agent Profiles (JSON format)

For Reddit-like platforms, agent profiles are typically stored in JSON format:

```json
[
  {
    "user_id": 0,
    "user_name": "user0",
    "name": "User Zero",
    "bio": "I am user zero with interests in technology.",
    "karma": 1000,
    "created_at": "2023-01-01"
  },
  {
    "user_id": 1,
    "user_name": "user1",
    "name": "User One",
    "bio": "Tech enthusiast and coffee lover.",
    "karma": 2000,
    "created_at": "2023-01-02"
  }
]
```

## Limiting Concurrent LLM Requests

To prevent overloading the LLM service, you can limit concurrent requests using the `semaphore` parameter:

```python
env = oasis.make(
    platform=platform,
    agent_profile_path="./data/profiles/users.csv",
    agent_models=models,
    available_actions=available_actions,
    semaphore=32,  # Limit to 32 concurrent LLM requests
)
```

## Complete Simulation Example

Here's a complete example of a simulation with all the advanced settings:

```python
import asyncio
import os
from datetime import datetime

import oasis
from oasis import ActionType, EnvAction, Platform, SingleAction
from oasis.social_platform.channel import Channel
from oasis.social_platform.typing import RecsysType
from oasis.clock.clock import Clock

from camel.models import ModelFactory
from camel.types import ModelPlatformType, ModelType

async def run_simulation():
    # Setup models
    models = ModelFactory.create(
        model_platform=ModelPlatformType.OPENAI,
        model_type=ModelType.GPT_4O_MINI,
    )

    # Define available actions
    available_actions = [
        ActionType.CREATE_POST,
        ActionType.LIKE_POST,
        ActionType.REPOST,
        ActionType.FOLLOW,
        ActionType.DO_NOTHING,
    ]

    # Setup custom time
    start_time = datetime(2023, 1, 1, 12, 0, 0)  # Jan 1, 2023, 12:00 PM
    sandbox_clock = Clock(magnification_factor=120)  # 120x speed

    # Database path
    db_path = "./data/custom_simulation.db"
    if os.path.exists(db_path):
        os.remove(db_path)

    # Setup custom platform
    channel = Channel()
    platform = Platform(
        db_path=db_path,
        channel=channel,
        sandbox_clock=sandbox_clock,
        start_time=start_time,
        recsys_type=RecsysType.TWHIN,
        refresh_rec_post_count=3,
        max_rec_post_len=5,
        following_post_count=2,
        show_score=False,
        allow_self_rating=False,
    )

    # Create environment
    env = oasis.make(
        platform=platform,
        agent_profile_path="./data/profiles/users.csv",
        agent_models=models,
        available_actions=available_actions,
        semaphore=64,
    )

    # Initialize the environment
    await env.reset()

    # Create initial actions
    action1 = SingleAction(
        agent_id=0,
        action=ActionType.CREATE_POST,
        args={"content": "First post in our simulation!"}
    )

    env_action1 = EnvAction(
        activate_agents=[0, 1, 2, 3, 4],
        intervention=[action1]
    )

    # Step 1: Run with initial post
    await env.step(env_action1)

    # Step 2: Activate a different set of agents
    env_action2 = EnvAction(activate_agents=[5, 6, 7, 8, 9])
    await env.step(env_action2)

    # Step 3: Run with all agents
    env_action3 = EnvAction()  # Empty action = all agents, no intervention
    await env.step(env_action3)

    # Clean up
    await env.close()

if __name__ == "__main__":
    asyncio.run(run_simulation())
```

## Analyzing Simulation Results

After running a simulation, the results are stored in the SQLite database specified by `db_path`. You can analyze these results using SQL queries or OASIS's built-in utilities:

```python
from oasis.testing.show_db import print_db_contents

# Print all database contents
print_db_contents("./data/simulation.db")
```

## Related Topics

- [Basic Environment Settings](/environment_settings/basic_settings)
- [Recommendation Settings](/environment_settings/recommendation_settings)
